CTextStream Class

Allows to read and write sequential text files (sometimes referred to as a text streams).

Works with ASCII and Unicode.

Works with Windows CRLF files and with Linux LF files.

Include file: AfxNova/CTextStream.inc

Constructors

Besides the default constructor, that initializes the COM library and creates an instance of the ITextStream interface, this additional constructor allows to create an instance of the class by passing a pointer to an existing ITextStream interface that becomes attached to the class (therefore, don’t release the passed pointer, it will be released by the CTextStream class).

CONSTRUCTOR CTextStream (BYVAL pstm AS Afx_ITextStream PTR)

Parameter	Description
pstm	Pointer to an instance of the Afx_ITextStream interface.

This allows to work with the standard StdIn, StdErr and StdOut streams using the methods of the CTextStream class.

#include "AfxNova/CTextStream.inc"
' // Create an instance of the CTextStream class initialized with a pointer to the standard StdOut stream
DIM pTxtStm AS CTextStream = CFileSys().GetStdOutStream(TRUE)   ' or FALSE to work with ansi
' // Write a string and an end of line to the stream
pTxtStm.WriteLine "This is a test."

Operators

Name	Description
LET	Initializes the class from an existing stream and attaches it.
CAST	Returns a pointer to the underlying ITextStream interface of the text stream object.

OPERATOR LET (BYVAL pstm AS Afx_ITextStream PTR)
OPERATOR CAST () AS Afx_ITextStream PTR

Parameter	Description
pstm	A pointer to the ITextStream interface of an existing text stream that will be attached to the class.

Methods and properties

Name	Description
Create	Creates a file and returns a TextStream object that can be used to read from or write to the file.
Open	Opens a file and returns a TextStream object that can be used to read from, write to, or append to the file.
OpenUnicode	Opens a file and returns a TextStream object that can be used to read from, write to, or append to the file.
OpenForInputA	Opens a file for input and returns a TextStream object that can be used to read from the file.
OpenForInputW	Opens a file for input and returns a TextStream object that can be used to read from the file.
OpenForOutputA	Opens a file for putput and returns a TextStream object that can be used to write to the file.
OpenForOutputW	Opens a file for putput and returns a TextStream object that can be used to write to the file.
OpenForAppendA	Opens a file for append and returns a TextStream object that can be used to write to the file.
OpenForAppendW	Opens a file for append and returns a TextStream object that can be used to write to the file.
Close	Closes an open TextStream file.
EOL	Returns TRUE if the file pointer is positioned immediately before the end-of-line marker in a TextStream file; FALSE if it is not.
EOS	Returns TRUE if the file pointer is at the end of a TextStream file; FALSE if it is not.
Read	Reads a specified number of characters from a TextStream file and returns the resulting string.
ReadLine	Reads an entire line (up to, but not including, the newline character) from a TextStream file and returns the resulting string.
ReadAll	Reads an entire TextStream file and returns the resulting string.
Write	Writes a specified string to a TextStream file.
WriteLine	Writes a specified string and newline character to a TextStream file.
WriteBlankLines	Writes a specified number of newline characters to a TextStream file.
Skip	Skips a specified number of characters when reading a TextStream file.
SkipLine	Skips the next line when reading a TextStream file.
Line	Returns the current line number in a TextStream file.
Column	Returns the column number of the current character position in a TextStream file.

Error and result codes

Name	Description
GetErrorInfo	Returns a description of the specified error code.
GetLastResult	Returns the last result code.
SetResult	Sets the last result code.

Create

Creates a specified file name and returns a TextStream object that can be used to read from or write to the file.

FUNCTION Create (BYREF wszFileName AS WSTRING, BYVAL bOverwrite AS BOOLEAN = TRUE, _
   BYVAL bUnicode AS BOOLEAN = FALSE) AS HRESULT

Parameter	Description
wszFileName	String expression that identifies the file to create.
bOverwrite	Boolean value that indicates whether you can overwrite an existing file. The value is true if the file can be overwritten, false if it can’t be overwritten. If omitted, existing files are not overwritten.
bUnicode	Boolean value that indicates whether the file is created as a Unicode or ASCII file. The value is true if the file is created as a Unicode file, false if it’s created as an ASCII file. If omitted, an ASCII file is assumed.

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

Example (Ansi text)

#include "AfxNova/CTextStream.inc"
USING AfxNova

' // Create an instance of the CTextStream class
DIM pTxtStm AS CTextStream
' // Create a text stream
DIM dwsFile AS DWSTRING = ExePath & "\Test.txt"
pTxtStm.Create(dwsFile, TRUE)
' // Write a string and an end of line to the stream
pTxtStm.WriteLine "This is a test."
' // Write more strings
pTxtStm.WriteLine "This is a string."
pTxtStm.WriteLine "This is a second string."
pTxtStm.WriteLine "This is the end line."

Example (Unicode text)

#include "AfxNova/CTextStream.inc"
USING AfxNova

' // Create an instance of the CTextStream class
DIM pTxtStm AS CTextStream
' // Create a text stream
DIM dwsFile AS DWSTRING = ExePath & "\TestW.txt"
pTxtStm.Create(dwsFile, TRUE, TRUE)
' // Write a string and an end of line to the stream
pTxtStm.WriteLine "This is a test."
' // Write more strings
pTxtStm.WriteLine "This is a string."
pTxtStm.WriteLine "This is a second string."
pTxtStm.WriteLine "This is the end line."

Open

Opens a specified file and returns a TextStream object that can be used to read from, write to, or append to the file.

FUNCTION Open (BYREF wszFileName AS WSTRING, BYVAL IOMode AS LONG = 1, _
   BYVAL bCreate AS BOOLEAN = FALSE, BYVAL bUnicode AS BOOLEAN = FALSE) AS HRESULT

Parameter	Description
wszFileName	String expression that identifies the file to open.
IOMode	Can be one of three constants: IOMode_ForReading, IOMode_ForWriting, or IOMode_ForAppending.
bCreate	Boolean value that indicates whether a new file can be created if the specified filename doesn’t exist. The value is True if a new file is created, False if it isn’t created. If omitted, a new file isn’t created.
bUnicode	Boolean value that indicates whether the file is created as a Unicode or ASCII file. The value is true if the file is created as a Unicode file, false if it’s created as an ASCII file. If omitted, an ASCII file is assumed.

The IOMode argument can have any of the following settings:

Constant	Value	Description
IOMode_ForReading	1	Open a file for reading only. You can’t write to this file.
IOMode_ForWriting	2	Open a file for writing.
IOMode_ForAppending	8	Open a file and write to the end of the file.

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

Example

#include "AfxNova/CTextStream.inc"
USING AfxNova

' // Create an instance of the CTextStream class
DIM pTxtStm AS CTextStream
' // Open file as a text stream
DIM dwsFile AS DWSTRING = ExePath & "\Test.txt"
pTxtStm.Open(dwsFile, IOMode_ForReading)
' // Read the file sequentially
DIM s AS STRING
DO UNTIL pTxtStm.EOS
   s = pTxtStm.ReadLine
   PRINT s
LOOP
pTxtStm.Close

OpenUnicode

Opens a specified file and returns a TextStream object that can be used to read from, write to, or append to the file.

FUNCTION OpenUnicode (BYREF wszFileName AS WSTRING, BYVAL IOMode AS LONG = 1, _
   BYVAL bCreate AS BOOLEAN = FALSE) AS HRESULT

Parameter	Description
cbsFileName	String expression that identifies the file to open.
IOMode	LONG. Can be one of three constants: IOMode_ForReading, IOMode_ForWriting, or IOMode_ForAppending.
bCreate	Boolean value that indicates whether a new file can be created if the specified filename doesn’t exist. The value is True if a new file is created, False if it isn’t created. If omitted, a new file isn’t created.

The IOMode argument can have any of the following settings:

Constant	Value	Description
IOMode_ForReading	1	Open a file for reading only. You can’t write to this file.
IOMode_ForWriting	2	Open a file for writing.
IOMode_ForAppending	8	Open a file and write to the end of the file.

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

Example

#include "AfxNova/CTextStream.inc"
USING AfxNova

' // Create an instance of the CTextStream class
DIM pTxtStm AS CTextStream
' // Open file as a text stream
DIM dwsFile AS DWSTRING = ExePath & "\TestW.txt"
IF pTxtStm.OpenUnicode(dwsFile, IOMode_ForReading) = S_OK THEN
   ' // Read the file sequentially
   DIM dws AS DWSTRING
   DO UNTIL pTxtStm.EOS
      dws = pTxtStm.ReadLine
      PRINT dws
   LOOP
   pTxtStm.Close
END IF

OpenForInputA

Opens a file for input and returns a TextStream object that can be used to read from the file. (Ansi version.)

FUNCTION OpenForInputA (BYREF wszFileName AS WSTRING, BYVAL bCreate AS BOOLEAN = FALSE) AS HRESULT

Parameter	Description
wszFileName	String expression that identifies the file to open.
bCreate	Boolean value that indicates whether a new file can be created if the specified filename doesn’t exist. The value is True if a new file is created, False if it isn’t created. If omitted, a new file isn’t created.

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

Example

#include "AfxNova/CTextStream.inc"
USING AfxNova

' // Create an instance of the CTextStream class
DIM pTxtStm AS CTextStream
' // ' // Open file for input as a text stream
IF pTxtStm.OpenForInputA(ExePath & "\Test.txt") = S_OK THEN
   ' // Read the file sequentially
   DIM s AS STRING
   DO UNTIL pTxtStm.EOS
      s = pTxtStm.ReadLine
      PRINT s
   LOOP
   pTxtStm.Close
END IF

OpenForInputW

Opens a file for input and returns a TextStream object that can be used to read from the file. (Unicode version.)

FUNCTION OpenForInputW (BYREF wszFileName AS WsTRING, BYVAL bCreate AS BOOLEAN = FALSE) AS HRESULT

Parameter	Description
wszFileName	String expression that identifies the file to open.
bCreate	Boolean value that indicates whether a new file can be created if the specified filename doesn’t exist. The value is True if a new file is created, False if it isn’t created. If omitted, a new file isn’t created.

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

Example

#include "AfxNova/CTextStream.inc"
USING AfxNova

' // Create an instance of the CTextStream class
DIM pTxtStm AS CTextStream
' // ' // Open file for input as a text stream
IF pTxtStm.OpenForInputW(ExePath & "\TestW.txt") = S_OK THEN
   ' // Read the file sequentially
   DIM dws AS DWSTRING
   DO UNTIL pTxtStm.EOS
      dws = pTxtStm.ReadLine
      PRINT dws
   LOOP
   pTxtStm.Close
END IF

OpenForOutputA

Opens a file for output and returns a TextStream object that can be used to write to the file. (Ansi version.)

FUNCTION OpenForOutputA (BYREF wszFileName AS WSTRING, BYVAL bCreate AS BOOLEAN = FALSE) AS HRESULT

Parameter	Description
wszFileName	String expression that identifies the file to open.
bCreate	Boolean value that indicates whether a new file can be created if the specified filename doesn’t exist. The value is True if a new file is created, False if it isn’t created. If omitted, a new file isn’t created.

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

Example

#include "AfxNova/CTextStream.inc"
USING AfxNova

' // Create an instance of the CTextStream class
DIM pTxtStm AS CTextStream
' // Open file for output as a text stream
IF pTxtStm.OpenForOutputA(ExePath & "\Test.txt") = S_OK THEN
   ' // Write a string and an end of line to the stream
   pTxtStm.WriteLine "This is a test."
   '// Close the file
   pTxtStm.Close
END IF

OpenForOutputW

Opens a file for output and returns a TextStream object that can be used to write to the file. (Unicode version.)

FUNCTION OpenForOutputW (BYREF wszFileName AS WSTRING, BYVAL bCreate AS BOOLEAN = FALSE) AS HRESULT

Parameter	Description
wszFileName	String expression that identifies the file to open.
bCreate	Boolean value that indicates whether a new file can be created if the specified filename doesn’t exist. The value is True if a new file is created, False if it isn’t created. If omitted, a new file isn’t created.

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

Example

#include "AfxNova/CTextStream.inc"
USING AfxNova

' // Create an instance of the CTextStream class
DIM pTxtStm AS CTextStream
' // Open file for output as a text stream
IF pTxtStm.OpenForOutputW(ExePath & "\TestW.txt") = S_OK THEN
   ' // Write a string and an end of line to the stream
   pTxtStm.WriteLine "This is a test."
   '// Close the file
   pTxtStm.Close
END IF

OpenForAppendA

Opens a file for append and returns a TextStream object that can be used to write to the file. (Ansi version.)

FUNCTION OpenForOutputA (BYREF wszFileName AS WSTRING, BYVAL bCreate AS BOOLEAN = FALSE) AS HRESULT

Parameter	Description
wszFileName	String expression that identifies the file to open.
bCreate	Boolean value that indicates whether a new file can be created if the specified filename doesn’t exist. The value is True if a new file is created, False if it isn’t created. If omitted, a new file isn’t created.

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

Example

#include "AfxNova/CTextStream.inc"
USING AfxNova

' // Create an instance of the CTextStream class
DIM pTxtStm AS CTextStream
' // Open file for append as a text stream
IF pTxtStm.OpenForAppendA(ExePath & "\Test.txt") = S_OK THEN
   ' // Write a string and an end of line to the stream
   pTxtStm.WriteLine "This is a test."
   '// Close the file
   pTxtStm.Close
END IF

OpenForAppendW

Opens a file for append and returns a TextStream object that can be used to write to the file. (Unicode version.)

FUNCTION OpenForAppendW (BYREF wszFileName AS WSTRING, BYVAL bCreate AS BOOLEAN = FALSE) AS HRESULT

Parameter	Description
wszFileName	String expression that identifies the file to open.
bCreate	Boolean value that indicates whether a new file can be created if the specified filename doesn’t exist. The value is True if a new file is created, False if it isn’t created. If omitted, a new file isn’t created.

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

#include "AfxNova/CTextStream.inc"
USING AfxNova

' // Create an instance of the CTextStream class
DIM pTxtStm AS CTextStream
' // Open file for append as a text stream
IF pTxtStm.OpenForAppendW(ExePath & "\TestW.txt") = S_OK THEN
   ' // Write a string and an end of line to the stream
   pTxtStm.WriteLine "This is a test."
   '// Close the file
   pTxtStm.Close
END IF

Close

Closes an open TextStream file.

FUNCTION Close () AS HRESULT

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

EOL

Returns TRUE if the file pointer is positioned immediately before the end-of-line marker in a TextStream file; FALSE if it is not.

FUNCTION EOL () AS BOOLEAN

Remark

The EOL (End of Line) property applies only to TextStream files that are open for reading; otherwise, an error occurs.

EOS

Returns TRUE if the file pointer is at the end of a TextStream file; FALSE if it is not.

FUNCTION EOS () AS BOOLEAN

Remark

The EOS (End os Stream) property applies only to TextStream files that are open for reading, otherwise, an error occurs.

Read

Reads a specified number of characters from a TextStream file and returns the resulting string.

FUNCTION Read (BYVAL numChars AS LONG) AS DWSTRING

Parameter	Description
numChars	LONG. Number of characters you want to read from the file.

Return value

A string with the characters read.

ReadLine

Reads an entire line (up to, but not including, the newline character) from a TextStream file and returns the resulting string.

FUNCTION ReadLine  () AS DWSTRING

Return value

A string with the content of the line read.

Example

#include "AfxNova/CTextStream.inc"
USING AfxNova

' // Create an instance of the CTextStream class
DIM pTxtStm AS CTextStream
' // Open file as a text stream
DIM dwsFile AS DWSTRING = ExePath & "\Test.txt"
IF pTxtStm.Open(dwsFile, IOMode_ForReading) = S_OK THEN
   ' // Read the file sequentially
   DO
     IF pTxtStm.EOS THEN EXIT DO
     DIM curLine AS LONG = pTxtStm.Line
     DIM dwsText AS DWSTRING = pTxtStm.ReadLine
     PRINT "Line " & STR(curLine) & ": " & dwsText
   LOOP
   '// Close the file
   pTxtStm.Close
END IF

ReadAll

Reads an entire TextStream file and returns the resulting string.

FUNCTION ReadAll  () AS DWSTRING

Return value

A string with the content of all the file.

Example

#include "AfxNova/CTextStream.inc"
USING AfxNova

' // Create an instance of the CTextStream class
DIM pTxtStm AS CTextStream
' // Open file as a text stream
DIM dwsFile AS DWSTRING = ExePath & "\Test.txt"
IF pTxtStm.Open(dwsFile, IOMode_ForReading) = S_OK THEN
   ' // Read all the contents of the file
   DIM dwsText AS DWSTRING = pTxtStm.ReadAll
   PRINT dwsText
   '// Close the file
   pTxtStm.Close
END IF

Write

Writes a specified string to a TextStream file.

FUNCTION Write (BYREF dwsText AS DWSTRING) AS HRESULT

Parameter	Description
dwsText	The text you want to write to the file.

Return value

The text you want to write to the file.

Example

#include "AfxNova/CTextStream.inc"
USING AfxNova

' // Create an instance of the CTextStream class
DIM pTxtStm AS CTextStream
' // Create a text stream
DIM dwsFile AS DWSTRING = ExePath & "\Test.txt"
IF pTxtStm.Create(dwsFile, TRUE) = S_OK THEN
   ' // Write strings
   pTxtStm.Write "This is a string."
   pTxtStm.Write "This is a second string."
   '// Close the file
   pTxtStm.Close
END IF

WriteLine

Writes a specified string and newline character to a TextStream file.

FUNCTION WriteLine (BYREF dwsText AS DWSTRING) AS HRESULT

Parameter	Description
dwsText	The text you want to write to the file. If omitted, a newline character is written to the file.

Return value

The text you want to write to the file.

Example

#include "AfxNova/CTextStream.inc"
USING AfxNova

' // Create an instance of the CTextStream class
DIM pTxtStm AS CTextStream
' // Create a text stream
DIM dwsFile AS DWSTRING = ExePath & "\Test.txt"
IF pTxtStm.Create(dwsFile, TRUE) = S_OK THEN
   ' // Write strings
   pTxtStm.WriteLine "This is a string."
   pTxtStm.WriteLine "This is a second string."
   '// Close the file
   pTxtStm.Close
END IF

WriteBlankLines

Writes a specified string and newline character to a TextStream file.

FUNCTION WriteBlankLines (BYVAL numLines AS LONG) AS HRESULT

Parameter	Description
numLines	LONG. Number of newline characters you want to write to the file.

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

Example

#include "AfxNova/CTextStream.inc"
USING AfxNova

' // Create an instance of the CTextStream class
DIM pTxtStm AS CTextStream
' // Create a text stream
DIM dwsFile AS DWSTRING = ExePath & "\Test.txt"
IF pTxtStm.Create(dwsFile, TRUE) = S_OK THEN
   ' // Write a string and an end of line to the stream
   pTxtStm.WriteLine "This is a test."
   ' // Write more strings
   pTxtStm.Write "This is a string."
   pTxtStm.Write "This is a second string."
   ' // Write two blank lines (the first will serve as an end of line for the previous write instructions)
   pTxtStm.WriteBlankLines 2
   pTxtStm.WriteLine "This is the end line."
   '// Close the file
   pTxtStm.Close
END IF

Skip

Skips a specified number of characters when reading a TextStream file.

FUNCTION Skip (BYVAL numChars AS LONG) AS HRESULT

Parameter	Description
numChars	LONG. Number of characters to skip when reading a file.

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

Example

#include "AfxNova/CTextStream.inc"
USING AfxNova

' // Create an instance of the CTextStream class
DIM pTxtStm AS CTextStream
' // Open file as a text stream
DIM dwsFile AS DWSTRING = ExePath & "\Test.txt"
IF pTxtStm.Open(dwsFile, IOMode_ForReading) = S_OK THEN
   ' // Read the file sequentially
   DO
     ' // Ext if we are at the end of the stream
     IF pTxtStm.EOS THEN EXIT DO
     ' // Current line
     DIM curLine AS LONG = pTxtStm.Line
     ' // Skip the 3rd line
     IF curLine = 3 THEN
        pTxtStm.SkipLine
        curLine + = 1
     END IF
     ' // Skip 10 characters
     pTxtStm.Skip 10
     ' // Current column
     DIM curColumn AS LONG = pTxtStm.Column
     ' // Read 5 characters
     DIM dwsText AS DWSTRING = pTxtStm.Read(5)
     ' // Skip the rest of the line
     pTxtStm.SkipLine
     PRINT "Line " + WSTR(curLine) + ", Column " +  WSTR(curColumn) & ": " + dwsText
   LOOP
   '// Close the file
   pTxtStm.Close
END IF

SkipLine

Skips the next line when reading a TextStream file.

FUNCTION SkipLine () AS HRESULT

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

Line

Read-only property that returns the current line number in a TextStream file.

PROPERTY Line  () AS LONG

Return value

LONG. The current line number.

Remarks

After a file is initially opened and before anything is written, Line is equal to 1.

Column

Read-only property that returns the column number of the current character position in a TextStream file.

PROPERTY Column  () AS LONG

Return value

LONG. The current column number.

Remarks

After a newline character has been written, but before any other character is written, Column is equal to 1.

GetLastResult

Returns the last result code.

FUNCTION GetLastResult () AS HRESULT

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

SetResult

Sets the result code.

FUNCTION SetResult (BYVAL Result AS HRESULT) AS HRESULT

Parameter	Description
Result	The error code returned by the methods.

GetErrorInfo

Returns a description of the last error code.

PRIVATE FUNCTION GetErrorInfo () AS DWSTRING

Error codes

Value	Description
&h800A0034	Bad file name or number
&h800A0035	File not found
&h800A0036	Bad file mode
&h800A0037	File is already open
&h800A0039	Device I/O error
&h800A003A	File already exists
&h800A003D	Disk space is full
&h800A003E	Input beyond the end of the file
&h800A0043	Too many files
&h800A0044	Device not available
&h800A0046	Permission denied
&h800A0047	Disk not ready
&h800A004A	Cannot rename with different drive
&h800A004B	Path/file access error
&h800A004C	Path not found